<html>
<head><meta charset="utf-8"><title>integrating reference more · t-lang/doc · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/index.html">t-lang/doc</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html">integrating reference more</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="225879525"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225879525" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225879525">(Feb 10 2021 at 17:52)</a>:</h4>
<p>I'd definitely like to talk more about how we can integrate the reference into the lang team.</p>



<a name="225879548"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225879548" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225879548">(Feb 10 2021 at 17:52)</a>:</h4>
<p>i'm kind of dropping this topic here as a placeholder</p>



<a name="225879567"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225879567" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225879567">(Feb 10 2021 at 17:52)</a>:</h4>
<p>I'm sorry I missed the audio meeting discussion-- was super busy--</p>



<a name="225879617"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225879617" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225879617">(Feb 10 2021 at 17:52)</a>:</h4>
<p>I think I might want to start a bit with what goals we are attempting to serve</p>



<a name="225879679"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225879679" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225879679">(Feb 10 2021 at 17:53)</a>:</h4>
<p>I have to thnk abot my own answer to that question, but I'd encourage people to just brainstorm a bit on what kinds of things they want to see</p>



<a name="225879699"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225879699" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225879699">(Feb 10 2021 at 17:53)</a>:</h4>
<p>I'll throw in a few to get things started from my perspective</p>



<a name="225879935"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225879935" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225879935">(Feb 10 2021 at 17:54)</a>:</h4>
<ul>
<li>A place where people can go to get answer to detailed questions</li>
</ul>



<a name="225879989"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225879989" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225879989">(Feb 10 2021 at 17:55)</a>:</h4>
<ul>
<li>Complete enough that I don't have to ask "do we need to update the reference?" but rather can just assume that's true =)</li>
</ul>



<a name="225880049"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225880049" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225880049">(Feb 10 2021 at 17:55)</a>:</h4>
<ul>
<li>Developing reference chapters should be part of the feature development process (it sort of is, but i think we can integrate much better)</li>
</ul>



<a name="225880189"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225880189" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225880189">(Feb 10 2021 at 17:56)</a>:</h4>
<ul>
<li>one question mark for me: I don't think the reference wants to be a <em>specification</em> -- i think it wants to be detailed enough for people to learn, but targeted at end users</li>
</ul>



<a name="225884113"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225884113" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Eric Huss <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225884113">(Feb 10 2021 at 18:24)</a>:</h4>
<p>Thanks for opening the topic!</p>
<p>My own opinion I think aligns with what you said. I think the reference is a good utility for learning the details, or more advanced topics. When I was first learning Rust, the "Patterns" chapter was one of the first things I saw in the Reference, and it helped me understand patterns much more clearly than other texts could (and it was one of the first chapters I worked on writing).</p>
<p>I think a non-goal for now is to make it a language spec, and I mainly say this because of our lack of resources. There's a bit of a gray area between "reference" and "spec", so it's not always clear what the difference is. However, I don't think it is possible to have a standards-level quality document with just a few volunteers randomly contributing, and I don't see that changing in the foreseeable future.</p>
<p>As for completeness, there are a few areas that have huge holes. Things like type inference, trait solving, and type checking are for the most part completely undocumented. Those are <em>huge</em> topics, so that is unlikely to change. I just started a chapter on <a href="https://doc.rust-lang.org/nightly/reference/names.html">name resolution</a>, but I suspect it will take a very long time for me to finish it. </p>
<p>So, I think it would be great if people assumed changes in rustc need to be reflected in the reference, with the caveat that the huge holes can be ignored.</p>
<p>I try to monitor PRs to see when language changes happen, but it is impossible for me to catch them all. Sometimes the PR description is too opaque for me to even know it is changing something. Sometimes the PR changes something accidentally. Sometimes the changes happen during review long after the PR has been opened, and I won't catch those. It would be great if more people were at least opening issues to track changes that are needed.</p>
<p>There is issue <a href="https://github.com/rust-lang/reference/issues/599">https://github.com/rust-lang/reference/issues/599</a> which goes into lower-level details about what the reference should be. I would like to make progress on some of those individual questions, but unfortunately I am spread thin and don't have much time.</p>



<a name="225903032"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225903032" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> oliver <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225903032">(Feb 10 2021 at 20:33)</a>:</h4>
<p>it seems at a glance that the stabilization PR doesn't specifically require<br>
consideration of documentation:<br>
<a href="https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#stabilization-pr">https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#stabilization-pr</a><br>
not having stabilized anything personally I can't speak from experience but it<br>
seems reasonable that a stabilization PR would present a review of relevant<br>
documentation so it can be examined with a view for sufficiency</p>



<a name="225925830"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225925830" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> isHavvy <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225925830">(Feb 10 2021 at 23:06)</a>:</h4>
<p>It used to be a requirement to include Reference documentation if needed, but it was dropped because of bandwidth issues.</p>
<p>Otherwise, what you said mirrors my thoughts. Part of the problem with building reference chapters early on is that the features often have changes that require changing of the reference material. The unsafe book is/was meant to be the area for working on documentation for features in progress, but I'm not sure how well that's panned out in practice.</p>



<a name="225925897"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225925897" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Eric Huss <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225925897">(Feb 10 2021 at 23:07)</a>:</h4>
<p>I think that stabilization guide does make it clear that the documentation should exist.  The very first section is about documentation, and the "Stabilization Report" includes the note to have "Links to the documentations (the PRs we have made in the previous steps)".   I think process-wise it should be clear that documentation should exist, but in reality people don't always do that.  Also, a lot of changes aren't exactly "stabilize this feature", but are more like "Accept tuple.0.0 as tuple indexing (take 2)".</p>



<a name="225926033"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225926033" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Eric Huss <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225926033">(Feb 10 2021 at 23:08)</a>:</h4>
<p>For the most part, stabilizations of big features have usually been handled well, with stabilization reports, and often PRs to the reference.  It's the random non-stabilization PRs that make it difficult.</p>



<a name="225929297"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225929297" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> oliver <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225929297">(Feb 10 2021 at 23:38)</a>:</h4>
<p>it seemed documentation for this process merely meant the recorded PR process<br>
[emphasis added] <code>Links to the documentations (*the _PRs_ we have made in the
previous steps*).</code> it wouldn't be unimaginable to have feature discussion and<br>
review form the 'documentations' though it might not be a very reasonable<br>
presentation to the user</p>



<a name="225929641"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225929641" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> oliver <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225929641">(Feb 10 2021 at 23:42)</a>:</h4>
<p>also fwiw my first reading of this suggested two distinct processes of<br>
'documentation PRs' and 'stabilization PRs' and not that those were necessarily<br>
related</p>



<a name="225930895"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/225930895" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> oliver <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#225930895">(Feb 10 2021 at 23:55)</a>:</h4>
<p>the unstable book does do this which I think is what @isHavvy meant to<br>
refer to i.e.:<br>
<a href="https://doc.rust-lang.org/nightly/unstable-book/language-features/associated-type-bounds.html">https://doc.rust-lang.org/nightly/unstable-book/language-features/associated-type-bounds.html</a>, also:<br>
<a href="#narrow/stream/237824-t-lang.2Fdoc/topic/how.20active.2Ers.20features.20land.20in.20the.20unstable.20book">https://rust-lang.zulipchat.com/#narrow/stream/237824-t-lang.2Fdoc/topic/how.20active.2Ers.20features.20land.20in.20the.20unstable.20book</a><br>
I had spent a minute or two looking through with a view to lift the<br>
information from the links though where I looked the basic information <em>is</em><br>
generally contained in the PRs and generally isn't unavailable</p>



<a name="227337030"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/227337030" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#227337030">(Feb 22 2021 at 21:04)</a>:</h4>
<p>I think we should overhaul the stabilization process</p>



<a name="227337062"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/227337062" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#227337062">(Feb 22 2021 at 21:04)</a>:</h4>
<p>I definitely think we should have a section in stabilization reports that includes links to reference PRs</p>



<a name="227337828"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/integrating%20reference%20more/near/227337828" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Eric Huss <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/integrating.20reference.20more.html#227337828">(Feb 22 2021 at 21:10)</a>:</h4>
<p>For most big feature stabilizations, that already happens most of the time (and the instructions <a href="https://rustc-dev-guide.rust-lang.org/stabilization_guide.html?highlight=report#write-a-stabilization-report">here</a> mention including links).   It's usually the smaller things that slip by without fanfare.</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>